<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
    <title>Chapter 14: Receivers</title>
    <link rel="stylesheet" type="text/css" href="../css/common.css" />
    <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
    <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen"/>    
  </head>
  <body onload="prettyPrint(); decorate();">
    <script type="text/javascript">prefix='../';</script>
    <script type="text/javascript" src="../js/prettify.js"></script>
    <script type="text/javascript" src="../templates/header.js"></script>
    <script type="text/javascript" src="../js/dsl.js"></script>
    <script type="text/javascript" src="../js/jquery-min.js"></script>
    <script type="text/javascript" src="../js/decorator.js"></script>
    <div id="left">      
      <noscript>Please turn on Javascript to view this menu</noscript>
      <script src="../templates/left.js" type="text/javascript"></script>
    </div>    
    <div id="right">
      <script src="menu.js" type="text/javascript"></script>
    </div>

    <div id="content">

      <h1>Chapter 14: Receivers</h1>

    <a href="receivers_ja.html">&#x548C;&#x8A33; (Japanese translation)</a>

      <div class="quote">

        <p><em>You cannot swim for new horizons until you have courage 
           to lose sight of the shore.</em></p>
  
        <p>&mdash;WILLIAM FAULKNER</p>
      </div>


      <script src="../templates/creative.js" type="text/javascript"></script>
      <script src="../templates/setup.js" type="text/javascript"></script>
    
      <h2 class="doAnchor" name="whatIsAReceiver">What is a Receiver?</h2>
    
      <p>A <em>receiver</em> is a Logback component that receives logging
      events from a remote appender and logs each received event according
      to local policy.  Using a combination of socket-based appenders and
      receivers, it is possible to construct sophisticated topologies
      for distribution of application logging events over a network.</p>
  
      <p>A receiver extends the <a
      href="../xref/ch/qos/logback/classic/net/ReceiverBase.html">
      <code>ch.qos.logback.classic.net.ReceiverBase</code></a> class.
      By virtue of the fact that a receiver extends this class, a
      receiver participates in the Logback component <a
      href="../xref/ch/qos/logback/core/spi/LifeCycle.html">LifeCycle</a>
      and a receiver is <a
      href="../xref/ch/qos/logback/core/spi/ContextAware.html">
      ContextAware</a>.</p>
    
      <p>Historically, support for logging event delivery over a network
      connection in Logback has been provided by <code>SocketAppender</code>
      and the corresponding <code>SimpleSocketServer</code>.  The appender
      acts as a client, initiating a network connection to the server
      application, and delivering logging events via the network connection.  
      The receiver component and corresponding appender support offers much 
      greater flexibility.</p>
    
      <p>A receiver component is configured in <em>logback.xml</em>, just
      like any other logback component.  This allows the full capabilities
      of <a href="onJoran.html">Joran</a> to be utilized in configuring
      a receiver component.  Moreover, <em>any</em> application can 
      receive logging events from remote appenders by simply configuring
      one or more receiver components.</p>
    
      <p>Connection initiation between an appender and a receiver 
      can occur in either direction.  A receiver can act in the role of a
      server, passively listening for connections from remote appender 
      clients.  Alternatively, a receiver can act in the client role,
      initiating a connection to a remote appender which is acting in the 
      server role.  Regardless of the respective roles of the
      appender and receiver, <em>logging events always flow from 
      the appender towards the receiver</em>.</p>
    
      <p>The flexibility to allow a receiver to initiate the connection
      to an appender is particularly useful in certain situations:
      </p>
      <ul>
        <li>For security reasons, a central logging server may be
          located behind a network firewall that does not allow incoming
          connections.  Using receiver components acting in the client
          role, the central logging server (inside the firewall) 
          can initiate connections to the applications of interest 
          (outside the firewall).
        </li>
        <li>It is often desirable for developer tools (such as IDE plugins)
          and enterprise management applications to have access to the
          logging event stream of running applications.  Traditionally,
          Logback has supported this (for example in Logback Beagle) by
          requiring the recipient application (e.g. a developer tool running
          in an IDE) to act in the server role, passively listening for 
          connections from a remote appender.  This can prove difficult to 
          manage, especially for tools running on a developer's workstation, 
          which may indeed by mobile.  However, such tools can now be 
          implemented using a Logback receiver component acting in the 
          client role, initiating a connection to a remote appender in 
          order to receive logging events for local display, filtering, 
          and alerting.
        </li>
      </ul>

      <p>A logback configuration can include any number of receiver components
      acting in any combination of the server or client roles.  The only 
      restrictions are that each receiver acting in the server role must
      listen on a distinct port, and each receiver acting in the client
      role will connect to exactly one remote appender.</p>
    
      <h2 class="doAnchor" name="receiverServerComponents">Receivers
      that Act in the Server Role</h2>
    
      <p>A receiver that is configured to act in the server role passively
      listens for incoming connections from remote appenders.  This is 
      functionally equivalent to using the standalone
      <code>SimpleSocketServer</code> application, except that by using
      the receiver component, <em>any</em> application that uses Logback
      Classic can receive logging events from remote appenders by simply
      configuring the receiver in <em>logback.xml</em>.</p>
        
      <p>
        <img border="1" src="images/chapters/receivers/serverSocketReceiver.png" "/>
      </p>

      <p>Logback includes two receiver components that act in the
      server role; <a
      href="../xref/ch/qos/logback/classic/net/server/ServerSocketReceiver.html">
      <code>ServerSocketReceiver</code></a> and its SSL-enabled
      subtype
      <a href="../xref/ch/qos/logback/classic/net/server/SSLServerSocketReceiver.html">
      <code>SSLServerSocketReceiver</code></a>.  Both of these receiver
      components are designed to accept connections from incoming
      <code>SocketAppender</code> (or <code>SSLSocketAppender</code>)
      clients.</p>
        
      <p>The <code>ServerSocketReceiver</code> components provide the 
      following configurable properties:</p>
    
      <table class="bodyTable striped">
        <tr>
          <th>Property Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="serverSocketReceiver">address</span></td>
          <td><code>String</code></td>
          <td>The local network interface address on which the receiver
          will listen.  If this property is not specified, the receiver
          will listen on all network interfaces.</td>
        </tr>
        <tr>
          <td><span class="prop" container="serverSocketReceiver">port</span></td>
          <td><code>int</code></td>
          <td>The TCP port on which the receiver will listen.  If this
          property is not specified, a default value will be used.</td>
        </tr>
        <tr>
          <td><span class="prop" container="serverSocketReceiver">ssl</span></td>
          <td><code>SSLConfiguration</code></td>
          <td>Supported only for <code>SSLServerSocketReceiver</code>, this
              property provides the SSL configuration that will be used by
              the receiver, as described in <a href="usingSSL.html">Using SSL</a>.
          </td>
        </tr>
      </table>
    
      <h3 class="doAnchor" name="usingServerSocketReceiver">Using
      ServerSocketReceiver</h3>
    
      <p>The following configuration uses the 
      <code>ServerSocketReceiver</code> component with a minimal local 
      appender and logger configuration.  Logging events received from
      a remote appender will be matched by the root logger and delivered
      to the local console appender.</p>
    
      <p class="example">Example: Basic ServerSocketReceiver Configuration
      (logback-examples/src/main/resources/chapters/receivers/socket/receiver1.xml)</p>

      <span class="asGroovy" onclick="return asGroovy('receiver1');">View as .groovy</span>
  <pre id="receiver1" class="prettyprint source">&lt;configuration debug="true">

  &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    &lt;encoder>
      &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n&lt;/pattern>
    &lt;/encoder>
  &lt;/appender>

  &lt;root level="DEBUG">
    &lt;appender-ref ref="CONSOLE" />
  &lt;/root>

  &lt;receiver class="ch.qos.logback.classic.net.server.ServerSocketReceiver">
    &lt;port>${port}&lt;/port>
  &lt;/receiver>

&lt;/configuration></pre>
  
      <p>Note that the receiver component's <em>class</em> 
      attribute identifies the receiver subtype that we wish to use.  In
      this example we are using <code>ServerSocketReceiver</code>.</p>
    
      <p>Our example server application is very similar in function and
      design to <code>SimpleSocketServer</code>.  It simply accepts a
      path for a logback configuration file as a command line argument,
      and runs the given configuration.  While our example is somewhat
      trivial, keep in mind that you can configure logback's 
      <code>ServerSocketReceiver</code> (or <code>SSLServerSocketReceiver</code>) 
      component in <em>any</em> application.
      </p>
    
      <p>From a shell in the <em>logback-examples</em> directory, 
      we can run our example server application as follows:</p>
    
      <p class="source">java -Dport=6000 <a href="../xref/chapters/receivers/socket/ReceiverExample.html">chapters.receivers.socket.ReceiverExample</a> \ 
      src/main/java/chapters/receivers/socket/receiver1.xml</p>
  
      <p>We can connect to the running receiver using a client application
      that is configured with a <code>SocketAppender</code>.  Our example
      client application simply loads a logback configuration that will
      connect a socket appender to our example receiver.  It then awaits
      input from the user in the form of a message that will be relayed to
      the receiver.  We can run the example client application as follows:
      </p>
    
      <p class="source">java -Dhost=localhost -Dport=6000 \
      <a href="../xref/chapters/receivers/socket/AppenderExample.html">chapters.receivers.socket.AppenderExample </a>\
      src/main/java/chapters/receivers/socket/appender1.xml</p>
    
      <h3 class="doAnchor" name="usingSSLServerSocketReceiver">Using
      SSLServerSocketReceiver</h3>

      <p>The following configuration repeats the same minimal appender
      and logger configuration, but uses the SSL-enabled receiver component
      that acts in the server role.</p>

      <p class="example">Example: Basic SSLServerSocketReceiver Configuration
      (logback-examples/src/main/resources/chapters/receivers/socket/receiver2.xml)</p>
      <span class="asGroovy" onclick="return asGroovy('receiver2');">View as .groovy</span>
  <pre id="receiver2" class="prettyprint source">&lt;configuration debug="true">

  &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    &lt;encoder>
      &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n&lt;/pattern>
    &lt;/encoder>
  &lt;/appender>

  &lt;root level="DEBUG">
    &lt;appender-ref ref="CONSOLE" />
  &lt;/root>

  &lt;receiver class="ch.qos.logback.classic.net.server.SSLServerSocketReceiver">
    &lt;port>${port}&lt;/port>
    &lt;ssl>
      &lt;keyStore>
        &lt;location>${keystore}&lt;/location>
        &lt;password>${password}&lt;/password>
      &lt;/keyStore>
    &lt;/ssl>
  &lt;/receiver>

&lt;/configuration></pre>

      <p>The essential differences between this configuration and the
      previous example using <code>ServerSocketReceiver</code> are the 
      specification of <code>SSLServerSocketReceiver</code> in the
      <em>class</em> attribute and the presence of the nested 
      <span class="prop">ssl</span> property, which is used here to 
      specify the location and password for the key store containing the 
      receiver's private key and certificate, using substitution variables. 
      See <a href="usingSSL.html">Using SSL</a> for details on 
      configuring SSL properties for Logback components.</p>    
 
      <p>We can run this configuration using the same example server
      configuration, with just a couple of additional configuration
      properties:</p>

      <p class="source">java -Dport=6001 \
      -Dkeystore=file:src/main/java/chapters/appenders/socket/ssl/keystore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.ReceiverExample \
      src/main/java/chapters/receivers/socket/receiver2.xml</p>
  
      <p>Note that the <em>keystore</em> property given on the command
      line specifies a file URL that identifies the location of the key 
      store.  You may also use a classpath URL as described in 
      <a href="usingSSL.html">Using SSL</a>.
      </p>
    
      <p>We can connect to the running receiver using a client application
      that is configured with a <code>SSLSocketAppender</code>.  We use 
      the sample example client application used in the previous example,
      with a configuration file that uses an SSL-enabled appender.  We
      run the example as follows:
      </p>
    
      <p class="source">java -Dhost=localhost -Dport=6001 \
      -Dtruststore=file:src/main/java/chapters/appenders/socket/ssl/truststore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender2.xml</p>
    
      <p>Note that our example is using a self-signed X.509 credential that 
      is suitable for testing and experimentation, only.  <strong>In a 
      production setting, you should obtain an appropriate X.509 credential 
      to identify your SSL-enabled logback components</strong>.  See 
      <a href="usingSSL.html">Using SSL</a> for more information.</p>
  
      <h2 class="doAnchor" name="receiverClientComponents">Receivers
      that Act in the Client Role</h2>
    
      <p>A receiver that is configured to act in the client role initiates
      a connection to a remote appender.  The remote appender must be a
      server type, such as <code>ServerSocketAppender</code>.</p>  
    
      <p>
        <img border="1" src="images/chapters/receivers/socketReceiver.png"/>
      </p>

      <p>Logback includes two receiver components that act in the client
      role; <a href="../xref/ch/qos/logback/classic/net/SocketReceiver.html">
      <code>SocketReceiver</code></a> and its SSL-enabled subtype
      <a href="../xref/ch/qos/logback/classic/net/SSLSocketReceiver.html">
      <code>SSLSocketReceiver</code></a>.  Both of these receiver
      components are designed to initiate a connection to a remote appender
      that is a <code>ServerSocketAppender</code> 
      (or <code>SSLServerSocketAppender</code>).</p>
        
      <p>The following configuration properties are supported by 
      <code>SocketReceiver</code> subtypes:</p>
    
      <table class="bodyTable striped">
        <tr>
        <th>Property Name</th>
        <th>Type</th>
        <th>Description</th>
        </tr>
        <tr>
          <td><span class="prop" container="SocketReceiver">remoteHost</span></td>
          <td><code>String</code></td>
          <td>The hostname or address of the remote server socket appender.</td>
        </tr>
        <tr>
          <td><span class="prop" container="SocketReceiver">port</span></td>
          <td><code>int</code></td>
          <td>The port number of the remote server socket appender.</td>
        </tr> 
        <tr>
          <td><span class="prop" container="socket">reconnectionDelay</span></td>
          <td><code>int</code></td>
          <td>
            A positive integer representing the number of milliseconds to wait
            before attempting to reconnect after a connection failure.  The
            default value is 30000 (30 seconds).
          </td>
        </tr>
        <tr>
          <td><span class="prop" container="SocketReceiver">ssl</span></td>
          <td><code>SSLConfiguration</code></td>
          <td>Supported only for <code>SSLSocketReceiver</code>, this
              property provides the SSL configuration that will be used for
              this receiver, as described in <a href="usingSSL.html">Using SSL</a>.
          </td>
        </tr>
      </table>
        
      <h3 class="doAnchor" name="usingSocketReceiver">Using
      SocketReceiver</h3>

      <p>The configuration used for <code>SocketReceiver</code>
      is quite similar to the previous example that used
      <code>ServerSocketReceiver</code>.  The differences relate to the 
      fact that the roles of client and server are reversed; a receiver
      of type <code>SocketReceiver</code> is a client, and the remote
      appender acts as a server.</p>
        
      <p class="example">Example: Basic SocketReceiver Configuration
      (logback-examples/src/main/resources/chapters/receivers/socket/receiver3.xml)</p>
      <span class="asGroovy" onclick="return asGroovy('receiver3');">View as .groovy</span>
  <pre id="receiver3" class="prettyprint source">&lt;configuration debug="true">
    
  &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">    
    &lt;encoder>
      &lt;pattern>%date %-5level [%thread] %logger - %message%n&lt;/pattern>
    &lt;/encoder>
  &lt;/appender>

  &lt;root level="DEBUG">
    &lt;appender-ref ref="CONSOLE" />
  &lt;/root>  

  &lt;receiver class="ch.qos.logback.classic.net.SocketReceiver">
    &lt;remoteHost>${host}&lt;/remoteHost>
    &lt;port>${port}&lt;/port>
    &lt;reconnectionDelay>10000&lt;/reconnectionDelay>
  &lt;/receiver>

&lt;/configuration></pre>
        
      <p>This configuration will cause logback to connect to a 
      <code>ServerSocketAppender</code> running on the host and port specified
      by the <em>host</em> and <em>port</em> substitution variables.  Logging
      events received from the remote appender will be logged locally 
      (according to the configuration shown here) via a console appender.
      </p>
   
      <p>Assuming you are in the <em>logback-examples/</em> directory, 
      you can run this example configuration using the following command:</p>

         

      <p>The example loads the configuration and then simply waits for logging
      events from the remote appender.  If you run this example when the remote
      appender is not running, you'll see <em>connection refused</em> messages
      appearing in the log output, periodically.  The receiver will 
      periodically attempt to reconnect to the remote appender until it 
      succeeds or until the logger context is shut down.  The delay
      interval between attempts is configurable using the 
      <span class="prop">reconnectionDelay</span> property as shown in the
      example configuration.
      </p>

      <p class="source">java -Dhost=localhost -Dport=6000 \
      chapters.receivers.socket.ReceiverExample \
      src/main/java/chapters/receivers/socket/receiver3.xml</p>


      <p>We can provide a remote appender to which our example receiver
      can connect, using the same appender example used previously.  The 
      example loads a logback configuration containing a 
      <code>ServerSocketAppender</code>, and then waits input from the
      user consisting of a message that will be delivered to connected
      receivers.  We can run the example appender application as follows:
      </p>

      <p class="source">java -Dport=6000 \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender3.xml</p>   

      <p>If you enter a message to send when the receiver is not connected,
      note that the message is simply discarded.</p>

      <h3 class="doAnchor" name="usingSSLSocketReceiver">Using
      SocketSSLReceiver</h3>


      <p>The configuration needed for <code>SSLSocketReceiver</code> is very 
      similar to that used with <code>SocketReceiver</code>.  The essential 
      differences are in the class specified for the receiver and the ability 
      to nest the <span class="prop">ssl</span> property to specify SSL 
      configuration properties.  The following example illustrates a basic 
      configuration:
      </p>
   
      <p class="example">Example: Basic SSLSocketReceiver Configuration
      (logback-examples/src/main/resources/chapters/receivers/socket/receiver4.xml)</p>
      <span class="asGroovy" onclick="return asGroovy('receiver4');">View as .groovy</span>
  <pre id="receiver4" class="prettyprint source">&lt;configuration debug="true">

  &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">    
    &lt;encoder>
      &lt;pattern>%date %-5level [%thread] %logger - %message%n&lt;/pattern>
    &lt;/encoder>         
  &lt;/appender>

  &lt;root level="DEBUG">
    &lt;appender-ref ref="CONSOLE" />
  &lt;/root>  
 
  &lt;receiver class="ch.qos.logback.classic.net.SSLSocketReceiver">
    &lt;remoteHost>${host}&lt;/remoteHost>
    &lt;port>${port}&lt;/port>
    &lt;reconnectionDelay>10000&lt;/reconnectionDelay>
    &lt;ssl>
      &lt;trustStore>
        &lt;location>${truststore}&lt;/location>
        &lt;password>${password}&lt;/password>
      &lt;/trustStore>
    &lt;/ssl>
  &lt;/receiver>

&lt;/configuration></pre>

      <p>Note that the <em>class</em> attribute now specifies 
      <code>SSLSocketReceiver</code> and that in addition to the configuration
      properties shown in the previous example, this configuration contains
      an SSL configuration specifying the location and password for a 
      trust store that will be used in validating that the remote appender is
      trusted.  See <a href="usingSSL.html">Using SSL</a> for more information 
      on configuring SSL properties.
      </p>
  
      <p>You can run this example configuration using the following command:</p>
  
      <p class="source">java -Dhost=localhost -Dport=6001 \
      -Dtruststore=file:src/main/java/chapters/appenders/socket/ssl/truststore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.ReceiverExample \
      src/main/java/chapters/receivers/socket/receiver4.xml</p>   
   
      <p>Once started, the receiver attempts to connect to the specified 
      remote appender.  Assuming that the appender is not yet running, you
      will see a "connection refused" message appearing in the log output
      periodically; the receiver will periodically retry the connection to
      the remote appender after delaying for the period of time specified by
      the <span class="prop">reconnectionDelay</span> property.
      </p>
  
      <p>We can provide a remote appender to which our example receiver
      can connect, using the same appender example used previously.  The 
      example loads a logback configuration containing a 
      <code>SSLServerSocketAppender</code>, and then awaits input from the  
      user consisting of a message that will be delivered to connected
      receivers.  We can run the example appender application as follows:
      </p>

      <p class="source">java -Dport=6001 \
      -Dkeystore=file:src/main/java/chapters/appenders/socket/ssl/keystore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender4.xml</p>   

      <p>If you enter a message to send when the receiver is not connected,
      note that the message is simply discarded.</p>

      <p>It is important to note once again that our example is using a 
      self-signed X.509 credential that is suitable for testing and 
      experimentation, only.  <strong>In a production setting, you should 
      obtain an appropriate X.509 credential to identify your SSL-enabled
      logback components</strong>.  See <a href="usingSSL.html">Using SSL</a> 
      for more information.</p>
  
        <script src="../templates/footer.js" type="text/javascript"></script>

    </div>
  </body>  
</html>
